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1.9 INTRODUCTION 


This is a users’ guide for a subsystem designed for 
long-term storage ot files. The system was originally 
intended for temporary use during the early development. of 
the BCC 5@W. Because of the turn of events, however, it is 
Still with us and probably will be throughout the life of 
the 506. In some ways the use of PFS has distinctly vosi- 
tive benefits; the user has good control over his files, 
their various back-up copies, and/or vrevious versions of 
them. Its principal disadvantages are that it requires’ the 
user to remember to write out his files before logging out 
of the system and its slightly different file-naming conven- 
tions from that of the basic 500 system. These are really 
minor, however, and the user should be able quickly to adapt 
to the use of PFS. 


Any large computing system making use of on-line access 
requires a means for storing and retrieving large quantities 
of information which must be accessed during computations. 
A common example of this is the storage of programs and data 
files which they require or generate. These files must be 
readily accessible, since it frequently costs much time to 
read them into the system over and over again from paper 
tape or card media. This 1s especially true for the remote 
user. 


Large operating systems facilitate on-line access ody 
providing mechanisms for naming and handling files and for 
Storing them, usually on disk. Unfortunately, even 
well-developed operating Systems are Subject to failure, and 
it is likely that valuable information can be lost at such 
times. The reasons for such loss mostly stem from the 
design of the operatina system’s directory structures. If 
they are damaged by the failure, then the system may become 
totally confused about its files. Approaches all requiring 
some tyve of redundancy in the directory structures can be 
used to remedy this serious problem, but most of them can 
lead to system inefficiencies, and, in any event, to added 
system complexity. 


The basic idea of PrS 1s to remove the permanent 
Storage of files from the duties of the operating system and 
assign the file storage to a user-level sub-system. PFS 1s 
designed ina very simple, straightforward manner, removing 
much of the flexibility of a fancier system, but providing a 
much higher degree of integrity for user files. 
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2.8 PFS DESIGN AND USE 


To accommodate PFS a portion of the disk file has been 
removed from the domain of the 50@9°s operating system. PFS 
accesses this portion of the disk file as a classical I/0 
device. That is, only PFS makes decisions concerning the 
allocation of the storage and the absolute addresses of the 
records being written or read from disk. Each system user 
is allocated a fixed area of this storage. The user's Space 
is divided into a number of pages, the first one of which is 
used for a file directory. The PFS directory vage nas a 
number of entries which are in one to one correspondence 
with the other pages in the user space. As files are copied 
into the PFS user space, the (non-directory) pages are 
filled on an as available basis. 


wnen the user logs in to the 5@8@ system, he usually 
finds that his files are not known by the System. Before 
proceeding, then, the user enters PFS and instructs it to 
copy the requisite files from the permanent Storage area 
into the operating systems file storage area. He then 
works with his files, and before leaving the system, he 
reenters PFS and instructs it to copy his undated files from 
the operating system back onto the permanent area. Because 
this operation is entirely manual and requires the user’s 
attention and consideration, and because the copying operat- 
ion. is relatively fast, the user's files are thus reasonably 
secure from system malfunctions. 


WARNING 


The user must remember that it is his 
responsibility to copy back to PFS those 
Files which he has changed during his 
computation session and that all his 


work will be lost if he forgets. Good 
practice requires that the user 
occasionally write out files which nave 
changed even during a session -- in case 


the system should go down after some 
reasonable amount of work. , 
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Satisfactory evidence of the merit of this approach is 
that ‘in over seven years of operation of PFS-like systems, 
Only a very small number of files nave been lost by operat- 
ing system or hardware malfunction. This should be contras- 
ted with other systems in which the apvoroach is to provide 
protection within the system itself; in such cases the 
losses Nave deen much greater. Of course, the user himself 
can foul up, and the hardware can fail: but these situations 
are tolerably low in frequency. 


As a matter of good practice, of course, users are 
reminded that it may be wise to write out a file onto the 
permanent Storage area at regular intervals as their console 
sessions progress (assuming the files are changing) so that 
in case of a system crash a relatively small amount of their 
work will be lost. 


Users can have access to the directories of other users 
in reasonablly controlled ways and can Share files. They 
can change the accessibility of their tiles to themselves 
and to other users and can do a number of other actions 
related to maintenance of their own directories. 


| The following 1s a simple summary of P¥S commands. The 
reader can easily learn to use PFS by reading it. 
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3.0 PFS COMMANDS 


Upon entering PrS, the user sees the PFS herald, “aN 
The user can then type one or more commands. The commands, 
except for arguments like file names, are generally 
One-letter commands, i1.e., the user types the first letter 
of the command and the rest of it is Supplied by PFS. Most 
of the commands must be confirmed by typing a “.". In the 
following, the characters which must be typed by the user 
are underlined; the characters “<“ and “>"“ are meta-Symbdols 
to designate the tyve of object which PFS expects. 


Three types of file names are mentioned below: <file 
name>, <disk file name>, and <system file name>. <system 
File name>s use the 5890 System file naming conventions. 
<disk file name>s have ae slightly different convention: 
names may not be longer than thirteen characters and must 
consist of letters, digits, “-"“, and “:"*. The term <file 
name> is used in those situations where the name is both a 
<disk file name> and a <system file name> and must therefore 
conform to an intersection of both naming conventions. 


It 1S possible under certain rules to refer to files 
belonging to other users, i.e., files in other users’ direc- 
tories. These files may be desiqnated by their usual file 
name, preceded by the directory-owner name; e.g., 


@<user name>:<disk file name> 


Thus, this document may be retrieved on-line from WWL’s 
directory by referring to it as 


@WWL: PFS-DOCUMENT 
P&S requires that user names -- when they are supplied 


-- be typed perfectly. If a user makes a typing error 
during a user name, he can abort the command by typing 


control-kK. The file name can njrave preceding characters 
removed by the use of control-A. As each control-A is 
typed, PFS echoes “"“" to signify backing up one character. 


If the user feels it 1S more convenient, he can also abort 
the command with a control-K. Typing two control-K’s in 
Succession will cause the user to leave PFS and return to 
the executive language processor. | 
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3.1 Leaving Pers 


The user may get out of PFS and return to the executive 
language processor by typing two control-K’s in succession. 
Alternatively he may use the PFS command: 


& FINISHED. 


3.2 Transfer Commands 


Only two commands actually do the transfers between 
disk and the system required for long-term storage and 
retrieval: READ and WRITE. Occasionally error diagnostics 
may accompany a transfer command. PFS is quite conservative 
about disk errors at the vresent time and reports any errors 


which occur without automatically retrying. Diagnostic 
messages are discussed in Section 4. All such messages 


Should be reported to hardware maintenance, and the command 
Should be immediately repeated. 


3.2.1 Copying a file from the system to PFS 
storage 


&WRITE DISK #fILE <file name>; (<reminder>) 


or &WRITE DISK FILE <disk file name>. (<reminder>) 
fROM <system file name>. 


Copies a file from the system onto the perman- 
ent storage area. The date & hour are recor- 
ded, and the file’s type is preserved. The 
reminder is one of two messages, (NEW) or 
(OLD), and serves to remind the user that he 
iS creating a new file or writing over an old 
one. Either Situation can occur as the result 
of an error on the part of the user. Note 
that if the user utilizes the short form of 
the command (i.e., terminates it with a “;"“) 
the reminder message occurs after the fact; 
the file will be written anyway. If the user 
utilizes the long form of the command (1.¢e., 
uses two “," terminators), the second “." 
Serves to confirm the data transfer after the 
reminder shows the user what he 1s about to 
do. Beginning users should use the long’ form 
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of tne command until they nave more confidence 
with Prs. 


3.2.2 Copying a file from permanent storage into 
the system 


&READ DISK FILE <file name>; 


Or &READ DISK FILE <disk file name>. 
TO <system file name>. 


Inverse of the write disk file command. 


3.3 File Directory Commands 


The uSer must be able to inspect the contents of his 
directory from time to time. Occasionally he may forget a 
file name, or he may want to see when he created it or last 
updated it. Files also have associated a number of other 
Parameters which he may want to inspect or to verify that a 
Change he has just made is correct. Too, users may want to 
look at other users” directories. The following commands 
facilitate the inspection and modification of directories 
and items contained within them. 


3.3.1 Listing the contents of a file directory 


& LIST. 
or &LIST FOR USER @<user name>:. 


The PFS directory for the indicated user 1s 
listed. All information concerning the 
various files for the user is printed for 
those items not invisible under access protec- 
tion. 
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Or 


Or 


or 


3.3.2 Listing only the file names within a direc- 
tory 


&BRIEF LIST. 
SBRIEF LIST FOR USER @<user name>:. 


Same as above except only the file names are 
printed. This command is frequently used when 
a user has forgotten the exact name of a _ file 
Or is looking for the presence of a file ina 
directory. It is faster than the LIST 
command. 


Se eo Looking at the parameters for a given file 


& EXAMINE FILE <file name>. 
&EXAMINE FILE @<user name>:<file name>. 


Prints all the information that LIST would 
print except only for the indicated file. 


3.3.4 Changing a file name 


& CHANGE FILE NAME <old_ name>. 
TO <new name>. 


&CHANGE FILE NAME @<user name>:<old name>. 
TO <new name>. | 


The use of the command 1s obvious. Users 
Cannot normally change the names of files in 
Other users’ directories as the second form of 
the command implies above. Section 3.3 
discusses file Sharing and vrotection. 
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Or 


Or 


3.3.5 Deleting a file from the directory 


&DELETE FILE <file name>. 
&DELETE FILE @<user name>:<file name>. 
The use of the command is obvious. ‘The space 


occupied by the file being deleted is avail- 
able for re-uSe. 


343%.5 Checking the amount of available disk 
Storage space 

& UNUSED SPACE. 

&UNUSED SPACE FOR USER @<user name>:. 


Prints the number of unused disk pages in the 
indicated user’s allocation. 
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3.4 file Accessibility Commands: File Sharing and Protec- 
tion | 


Files written on the disk are provided with one of 
several levels of access to each of three classes of users: 
its owner(s), the public, and to that subset of the public 
who may know a special password associated with the file. 
These accesses are called respectively, owner access, 
general access, and password access. _ 


Bach access class may have one of four levels: invis- 
ible (-), inaccessible (N), read-only (R), and read-write 


(W). When a file is first written it Is given the initial 
accesses: 


owner: W 
password: - (- means here “no access") 
general: N 


Thus the newly-created file is read-write to its owner(s) 
and inaccessible to all others. 


The reader will recall that the users of PFS may list 
the directories of other users and attempt to read or write 
their files. The algorithm used by PFS to check an = attemp- 
ted access for validity is Straightforward: first a check 
is made to see whether the user attempting the access 1S. an 
Owner: if so, then is the nature of the access legal? If 
the ownershiv test fails, then does the password (if one is 
typed) match; and if so, is the nature of the access now 
legal? Finally, is the attempted access legal for general 
users? If the answer to all these questions is no, the 
access is denied. When a user lists the contents of a 
directory -which he does not own, all files marked invisible 
will be skipped. 


Ownership of a directory 1S required to be able to 
execute several PFS commands. Users cannot, for example, 
CHANGE or DELETE file names without ownership status. 
Ownership is also required to do those commands which change 
the accesses from their initial values. These commands are 
given below. 


Files with passwords associated with them are referred 
to much aS a general user reference is made, i1.e., by 
Specifying a user name with the file name, except the pass- 
word is supplied in parentheses after the user name. PFS 
does not echo the password. For example, a password 
reference would be typed as: 


Q@WWL (<password>) :SOME-FILE 
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Because of the non-echoing password the file name 


appear on the terminal as 


Or 


or 


Q@wWWL() :SOME-FILE 


3.4.1 Changing general access to files 


&GENERAL ACCESS TO FILE <file name>. 
1S —/N/R/We 


&GENERAL ACCESS TO FILE @<user name>:<file name>. 


1S -/N/R/W. 


The construct -/N/R/W means - or N or R or 
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would 


W. 


- means the file iS invisible; general users 


Cannot see the file in a directory listing. 


N 


Stands for inaccessible; general users can see 


it in the directory but can’t get at it. 
for read-only, and W means read-write. 


3.4.2 Changing password access to files 


& PASSWORD ACCESS TO FILE <file name>. 
IS (<password>) -/N/R/W. 


Ris 


&PASSWORD ACCESS TO FILE @<user name>:<file name>. 


IS (<password>)-/N/R/W. 


Same as above, but for password access. 


In 


this case the “-“ stands for “no such access." 
It 1s used to remove existing password access 
for a file. In this case the password portion 


1s echoed to the user as confirmation of 
new password. 


the 
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3.4.3 Changing owner access to files 


&OWNER ACCESS TO FILE <file name>. 
IS 2/N/R/We 


or &OWNER ACCESS TO FILE @<user name>:<file name>. 
Is —/N/R/We 


Same aS above, but for owner access. If an 
Owner wants to prevent himself from overwrit- 
ing an important file, he can, for example, 
set his owner access to read-only. Of course, 
he can set it back whenever he wishes. 


3.5 Pseudo-ownership and Abbreviations: More File Sharing 


Most files are owned by the user creating them; they 
contain information of interest only to him and remain under 
his private jurisdiction. Some files, however, are of wider 
interest. While the owner may wish to retain the privilege 
of modifying them, others may have the right to read _ them. 
Files in this category are easily handled by means of 
general and password accesses. Some files may need to be 
written occasionally by others. Again the password access 


mechanism will suffice for this situation. Finally, how- 
ever, there iS a small number of files which require 
Frequent read-write access by several individuals. . The 


password mechanism becomes cumbersome if it must be used too 
freguently. | 


PFS provides a means by which several users may enjoy 
almost all the privileges of ownership of files in a given 
directory. This status is called pseudo-ownership, and 
users having it are called friends of the directory owner. 
Friends can execute all of the operations and commands’ the 
directory owner can do except modify the list of friends of 
the owner. There may be aS many as twelve friends of any 
directory owner. 


The list of friends may be set or modified by the 
following command: 
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3.5.1 Equating an item number to a user name 


&MODIFY ITEM #<item number>. 
TO USER @<user name>:. 7 


This command permits the owner to change the 
friend list for his directory. His friends 
are designated by the numbers 1] through 12. 
The friend list is given in the directory 
listing by the LIST command. A user name may 
De removed from the list oy typing “-" in 
place of the expected user name. | 


The MODIFY ITEM command permits two additional items to 
be set to user names. Item 13 determines the identity of a 
user who may be referred to merely by “<"“, and item 14 
determines who is ">", These two symbols may be used in 
place of a user name at any point in PFS. Thus if a given 
user is himself the friend of another user and finds himself 
doing file operations frequently in that other user’s direc- 
tory, the symbols "“"<" and ">" can greatly facilitate his 
references. 


For example, it 1S much easier to type 
<SHARED-FILE. 
than it is to type 
@LICHTENBERGER: SHARED-FILE. 


Items 13 and 14 may be returned to null by means of the 
MODIFY ITEM command, specifying “-“ in place of the expected 
user name. | 


It may be that a uSer has a number of files which he 
wants accessed by friends but others he wants to keep 
private. PFS does not provide a finer access control than 
those mechanisms previously mentioned. It is possible, how- 
ever, to remedy the situation just mentioned, especially 
when a number of uSers are working on a Similar project. 
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A fictitious user directory can be established. (This 
Cannot be done just to accommodate a few files.) No user of 
the system is then the true owner of tne directory, and a 
number of users can eStablish themselves as friends of the 
directory and interact accordingly. All that remains is to 
provide a means for these mutual owners to change the 


constitution of the friend list. To do this they must 
become, for the moment, the real owner. This is done by 
tricking PFS -- with the following command -- into assuming 


a new identity for the user. 


The command, which detaches the user from his own PFS 
directory and attaches him to the new directory, 1S: 


3.5.2 Attaching the user to a new directory 


@<user name>: (<password>). 


When a user enters PFS, he is given the direc- 
tory associated with his name. If for some 
reason he wishes to assume a new identity, 
1.¢., take over the directory of someone else, 
then he uses this command. But he must know 
the password of the new user. This password 
is identical to the new user’s TSS password. 
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3.6 


Miscellaneous Commands 


PFS contains a few other commands which 


Occasionally useful. These are listed below. 


Or 


or 


Or 


3.6.1 Verifying the integrity of the user's data 


& VERIFY DATA. 
&VERTIFY DATA FOR USER @<user name>. 


The entire set of disk vages is read one at a 
time for error checking vdurvoses. If a disk 
error is encountered, a diagnostic message is 
typed giving the physical disk address and the 
nature of the error. Such episodes’ should 
always be reported to the hardware people for 
investigation. Normally, the use of this 
command should not be required, as all disk 
pages are reread upon writing, and their con- 
tents are compared with that of the original 
system file. 


3.6.2 Typing out correspondence of file pages with 
physical disk pages 

&STATUS. 

&STATUS FOR USER @<user name>:. 
Prints the contents of the PFS directory show- 


ing the utilization of the various physical 
disk pages allocated to the indicated user. 


3.6.3 Permanently discard physical disk page from 
user directory | 


& ABANDON FILE <file name>. 


&ABANDON FILE @<user name>:<file name>. 


14 


are 
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Ownership access is required. Command works 
precisely like delete file except that as the 
File is deleted, each page is read once for 
possible errors. If an error is encountered, 
the vage involved is marked as bad and is 
permanently removed from the user’s available 
Space so aS not to cause further difficulty 
for the user. The hardware maintenance people 
should be informed of any disk pages which are 
deleted aS a consequence of the use of this 
command. The command should be regarded as an 
extreme measure. 


3.6.4 Conversing with another user in PFS 
&"<arbitrary text> 


If another user links to a given user while he 
is in PFS, the “ command causes PFS to ston 
interpreting commands or file names and permit 
the uSer to carry out a conversation of arbi- 
trary length (any number of carriage returns 
can be included in the text). The user 
escapes from this mode with control-kK. 


PFS Reference Manual May 1, 1974 Page 16 
4.8 PFS ERROR MESSAGES 


PFS does a considerable amount of checking for various 
kinds of errors. The integrity of the users’ files depends 


on the various checks that are done. The disk file unit 
reports several typnes of data transfer errors, but P#S 
checks data further. Fach directory as it 1s read is 


checked for correctness of content; this is also done before 
writing the directory after updating. Each data block writ- 
ten on the disk is re-read during the writing operation and 
compared with the correct information. 


All these checks and others give rise to the following 
error messages and their interpretations. 


NOT ENOUGH ROOM 


This message signifies that the file to be 
written will not fit into the available space 
on the disk. The standard remedy is to list 
the directory contents. This usually reveals 
some junk files which can be deleted to make 
room. 


This message means that the user is attempting 
an operation which is imvoroper. The user may 
be denied the attempted access or he may have 
typed an incorrect file name, user name, or 
password. BaSically the message means to 
think more carefully and try again. 


REREAD ERROR 


This message is typed during a WRITE operation 
if the data is somehow written incorrectly on 
the disk. The checking operation is Similar 
to the read-after-write checks done by magne- 
tic tape units. The user should repeat’ the 
WRITE command. The message includes track, 
Oband, sector, and unit information which 
Should be reported to hardware maintenance 
personnel. 
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TSU DUMP.. e 


This message iS given by any read error detec- 
ted by the disk hardware. Track, band, 
Sector, and unit information is included in 


the message, and it should be reported 
promptly to hardware maintenance personnel. 
The user should repeat his command -- perhavs 


Several times. 


COMPARE ERROR 


This message indicates catastrophic failure of 
the disk controller. It should occur with far 
less frequency than virtually any other 
message. Occurrences Should be immediately 
reported to hardware maintenance personnel. 


CANT WRITE INDEX 


The user has performed some strange sequence 
of actions, or a bug in PFS, has caused the 
directory to become diSarranged. The user 
Should repeat his command. Failing a second 
time, he should leave PFS and re-enter. 


INDEX FORMAT ERROR 
CAN’T READ INDEX 
INDEX CLOBBERED 


These messages result from various checks on 
the directory as it is read from disk. The 
user should retry and 1f he cannot get’ the 
directory to read successfully he should 
contact operations personnel. 


DRUM ERROR, BLOCK ... 


Catastrophic system error which can never 
occur. | 7 
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